home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 5 / Amiga Tools 5.iso / grafik / 3d & render tools / irit / www / home / coding.std < prev    next >
Text File  |  1996-07-16  |  10KB  |  341 lines
  1. These are the coding standards I am using. If you make some changes to the
  2. code, please attempt to follow these rules.
  3.  
  4. Gershon Elber
  5.  
  6. gershon@cs.technion.ac.il
  7.  
  8. Compile with IRIT makefile/flag tools to ensure maximum warnings. Attempt
  9. to minimize the number of warnings.
  10. ------------------------------------------------------------------------------
  11.  
  12.  
  13. GENERAL
  14. -------
  15.  
  16. Code should not exceed column 80. If the code is going to "look"
  17. better with more that 80 columns it is allowed but should be
  18. restricted as possible.
  19.  
  20. NESTING
  21. -------
  22.  
  23. Nesting of all expressions is by 4 spaces. Tabs used are 8 spaces.
  24.  
  25. SPACES
  26. ------
  27.  
  28. No spaces are allowed after '(' and before ')' in a function call or
  29. math expression. However, spaces are allowed between arguments after
  30. the comma or between operations:
  31.  
  32.     sin(x);
  33.     Function1(x, y, z);
  34.     x + 5 * sin(y);
  35.  
  36. FUNCTION HEADER'S COMMENT
  37. -------------------------
  38.  
  39. Function comments will have the following form:
  40.  
  41. /*****************************************************************************
  42. * DESCRIPTION:                                     M
  43. * Multi line description of the function. This is a text that will be copied M
  44. * to the programmer's manual iff the end of the line is M instead of a *     M
  45. * like this line.                                 M
  46. *   If a V is found at the end of the line, it is copied Verbatim. Example:  M
  47. * A x + B y + C z + D w + E = 0 defines an hyper plane in four space.        V
  48. *                                         M
  49. *   Proper indentation will be given to algorithms or sequences that begin   M
  50. * with an alpha-numeric values followed by a point. For example:             M
  51. *                                         M
  52. * 1. One letter    which sets the option letter (i.e. 'x' for option '-x').     M
  53. *    1.1 Allow even sub sequences.                         M
  54. * 2. '!' or '%'    to determines if this option is    really optional    ('%') or     M
  55. *    it    must be provided by the user ('!').                     M
  56. * 3. '-' always.                                 M
  57. * 4. Sequences that start with either '!' or '%'.                 M
  58. *       Each sequence will be followed by one or two characters    which        M
  59. *    defines the kind of the input:                            M
  60. *    4.1 d, x, o, u - integer is expected (decimal, hex, octal base or         M
  61. *          unsigned).                             M
  62. *    4.2 D, X, O, U - long integer is expected (same as above).             M
  63. *    4.3 f - float number is expected.                         M
  64. *                                         *
  65. * PARAMETERS:                                     M
  66. *   I1: one per line, must have an M at the end to show up in prog manual.   M
  67. *   C2: this parameter is the second one.                     M
  68. *                                         *
  69. * RETURN VALUE:                                     M
  70. *   int: Number of manuals to create.                         M
  71. *                                         *
  72. * SEE ALSO:                                                                  M
  73. *   ProgrammerManual2, ReferenceManual                         M
  74. *                                                                            *
  75. * KEYWORDS:    (only if a global non static function).                 M
  76. *    ProgrammerManual, manual, documentation                     M
  77. *****************************************************************************/
  78. int ProgrammerManual(int I1, char C2)
  79. {
  80. }
  81.  
  82. Functions that are obviously auxiliary can have the postfix Aux, must be
  83. static, and can have documentation as:
  84.  
  85. /*****************************************************************************
  86. * DESCRIPTION:                                                               *
  87. * Auxiliary function to function SymbPiecewiseRuledSrfApprox             *
  88. *****************************************************************************/
  89. static CagdSrfStruct *CagdPiecewiseRuledSrfAux(CagdSrfStruct *Srf,
  90.                            CagdBType ConsistentDir,
  91.                            CagdRType Epsilon,
  92.                            CagdSrfDirType Dir)
  93.  
  94. The function comment must be followed very precisely so they could be
  95. grabbed out of the code directly into the programmer's manual. If you
  96. are using the emacs editor (If you dont, you better switch to it), add
  97. irit.el from the irit subdirectory to your .emacs. This emacs-lisp file
  98. contains a definition for make-irit-c-function which expands a skeleton
  99. from a given prototype. Once irit.el is installed, type
  100. 'M-x make-irit-c-function' followed by a function prototype 'int Test(char c)'.
  101.  
  102. Static functions will never have 'M' or 'V' as last character in line. Only
  103. '*'. The 'SEE ALSO' section is recommended but optional.
  104.  
  105. INTERNAL COMMENTS
  106. -----------------
  107.  
  108. Internal comments will be aligned to the right to column 80 if the
  109. are commenting expression in the same line:
  110.  
  111.     i %= 2;                              /* Is i even? */
  112.  
  113. Comments that explains the following block, will be left aligned as
  114. the block. The comment does not need to be right aligned to column 80
  115. as well:
  116.  
  117.     /* This is a comment for the next line. */
  118.     i %= 2;
  119.  
  120. All comments should be properly Capitalized and terminate with a point.
  121.  
  122. FUNCTION AND VARIABLE NAMES
  123. ---------------------------
  124.  
  125. Both function and variable names will have NO UNDERSCORES. Words will be
  126. capitalized to distinguish them from each other. Variables of single
  127. character will be lower case. Examples of valid names:
  128.  
  129.     ThisIsAFunction, VariableOne, X1, i, j
  130.  
  131. Defined types (via typedef) will hint on themselves. A type of a
  132. structure will end with "Struct", for example CagdSrfStruct or
  133. IPPolygonStruct. Otherwise, a name of a typedef will end with "Type". For
  134. examples MatrixType or RealType.
  135.  
  136. STRUCTURES and UNIONS
  137. ---------------------
  138. Structures must be typedef defined. If next and prev slots are allocated,
  139. they must be called Pnext and PPrev respectively. If an attribute slot is
  140. also used, it must be called Attrs.
  141.  
  142.  
  143. VARIABLE'S DECLARATIONS
  144. -----------------------
  145. Variables will be declared at the deepest nesting possible. That is, if
  146. a variable is used in one module, it will be static to the module. If the
  147. variable is used in one function, it will be defined in one function. If
  148. a variable is used in one block in one function, it will be defined in that
  149. block. Variables will be declared static first, followed by automatic.
  150. Variables will be declared from simple type to complex/composed ones.
  151. Variables that are intialized are to be declared one per line, indented
  152. once from the indentation level of the variable type. Example:
  153.  
  154.     static int
  155.     LastCount = 0;
  156.     static RealType
  157.     LastValue = 0.0;
  158.     static IPObjectStruct *TmpObj;
  159.     char Str[LINE_LEN], *p,
  160.     *Name = "MyName";
  161.     int Dir = REAL_PTR_TO_INT(RDir),
  162.     OldOrder = Dir == CAGD_CONST_U_DIR ? Srf -> VOrder : Srf -> UOrder,
  163.     NewOrder = REAL_PTR_TO_INT(RNewOrder);
  164.     IPObjectStruct *SrfObj;
  165.     CagdSrfStruct *TSrf,
  166.     *Srf = PObjSrf -> U.Srfs;
  167.  
  168. Do not use the register modifier.
  169.  
  170. PARAMETERS OF FUNCTIONS
  171. -----------------------
  172.  
  173. Parameters of function prototypes will either be all in one line:
  174.  
  175.     int Func1Test(int Len, RealType *Vect)
  176.  
  177. or all arguments must be aligned one below the other:
  178.  
  179.     static CagdSrfStruct *CagdPiecewiseRuledSrfAux(CagdSrfStruct *Srf,
  180.                                CagdBType ConsistentDir,
  181.                                CagdRType Epsilon,
  182.                                CagdSrfDirType Dir)
  183.  
  184. Local (to a file) functions must be declared static and a prototype of the
  185. function should also be placed in the beginning of the file. Otherwise,
  186. for a non static function, a prototype must be place in the appropriate
  187. header ('.h' file) file.
  188.  
  189. MACROS
  190. ------
  191.  
  192. All macros that are local to a file will be defined at the beginning of
  193. the file after the #include statements. All the names of the macros will
  194. be in uppercase and words seperated by underscore:
  195.  
  196. #define LINE_LEN_VLONG    1024    /* Lines read from stdin/files... */
  197. #define MIN(x, y)        ((x) > (y) ? (y) : (x))
  198.  
  199.  
  200. POINTERS and SLOTS
  201. ------------------
  202. Points should be seperated before and after with a space:
  203.  
  204.     X = P -> Coords[1];
  205.  
  206. This is not the case for slots of a structure:
  207.  
  208.     X = P.Coords[1];
  209.  
  210.  
  211. BLOCKS
  212. ------
  213.  
  214. Blocks starts with '{' and ends with '}'. If the block is beginning of
  215. function then it will start with '{' at column 1 and end at column 1
  216. with '}'. Otherwise, it will start with some expression as for/if/while
  217. etc. in the nesting form: 
  218.  
  219.     expression {
  220.     .
  221.     .
  222.     .
  223.     }
  224.  
  225. FOR
  226. ---
  227.     for (x = 0; x < 10; x++)
  228.  
  229.     or
  230.  
  231.     for (x = 0, i = 1;
  232.          x < 5;
  233.          x++, i--)
  234.  
  235.     The body of the for loop can never be in the same line where the ')'
  236.     is. The ')' will be followed by '{' and the body will start in the next
  237.     line nested 4 space deapper:
  238.  
  239.     for (....)
  240.         x = sin(j);
  241.     or
  242.     for (....) {
  243.         x = y / j;
  244.         y = j + 2;
  245.     }
  246.  
  247. WHILE
  248. -----
  249.     while (x > 0)
  250.         x--;                       /* Better use x = 0! */
  251.  
  252. or
  253.  
  254.     while (x > 0 && y > 0) {
  255.         x -= 4;
  256.         y -= 4;
  257.     }
  258.  
  259. or
  260.  
  261.     while (x > 0 &&
  262.            x < 5)
  263.         x /= 2;
  264.  
  265.  
  266. IF
  267. --
  268.  
  269.     if (x > 0)
  270.         x = -x;
  271.  
  272. or
  273.  
  274.     if (x > 0 && y > 0) {
  275.         x = -x;
  276.         y = -y;
  277.     }
  278.  
  279. or
  280.  
  281.     if (x > 0)
  282.         x = -x;
  283.     else
  284.         x /= 2;
  285.  
  286. or
  287.  
  288.     if (x > 0)
  289.         x = -x;
  290.     else if (x < -100)
  291.         x /= 20;
  292.     else
  293.         x /= 2;
  294.  
  295. If an if expression has an else clause both bodies will be aligned 4
  296. space deep (The body of the if clause can not be in same line as the
  297. if and must be aligned with the else body).
  298.  
  299.  
  300. SWITCH
  301. ------
  302.  
  303.     switch (i) {
  304.         case 1:
  305.         printf("1");
  306.         break;
  307.         case 2:
  308.         printf("2");
  309.         break;
  310.         case 3:
  311.         printf("3");
  312.         break;
  313.         default:
  314.         printf("Too big");
  315.         break;
  316.     }
  317.  
  318. GENERAL PROGRAMMING
  319. -------------------
  320.  
  321. For portability, you should use IritMalloc, IritRealloc and IritFree
  322. for dynamic memory maintenance. For this same reason you should also
  323. use IritRandom/IritRandomInit and IritSleep, IritCPUTime and
  324. IritRealTimeDate, whenever appropriate. Employ the macros defined in
  325. irit_sm.h as much as possible.
  326.  
  327. FINAL REMARK
  328. ------------
  329.  
  330. If you are still not sure how the code should be formated in some specific
  331. case, consult the code. Out of over 100k of lines of code, you are most
  332. likely to find a similar case to yours.
  333.  
  334. Write your code as if it is going to become a library. Isolate and
  335. encapsulate everything as much as possible. For modules that performs
  336. a specific task, isolate the access to a small set of accessor
  337. functions that have unique names using a prefix that hints on the
  338. functionality of the module. If you must have macros and/or global
  339. variables that are accessible to the world, make them uniquely
  340. prefixed in a similar manner.
  341.